C API/Array
The functions described here create and manipulate arrays. Creating an array VALUE rb_ary_new(void); VALUE rb_ary_new2(long capa); VALUE rb_ary_new3(long n, ...); VALUE rb_ary_new4(long n, const VALUE *elts); rb_ary_new and rb_ary_new2 creates a new array with zero elements. rb_ary_new2 also reserves space for capa elements, but the reported size is still zero. rb_ary_new3 creates a new array with n elements. n is followed by n instances of VALUE, each designating an element of the new array. rb_ary_new4 creates a new array with n elements. The C array elts has n elements, each designating an element of the new array. The return value is the new array. ---- VALUE rb_ary_dup(VALUE ary); rb_ary_dup returns a shallow copy of the array ary. ---- VALUE rb_assoc_new(VALUE car, VALUE cdr); rb_assoc_new creates a two element array, whose elements are car and cdr. The return value is the new array. ---- VALUE rb_get_values_at(VALUE obj, long olen, int argc, VALUE *argv, VALUE(*func)(VALUE, long)); rb_get_values_at creates an array by calling func(obj, NUM2LONG(argvi)) once for each i from 0 to argc-1. If a Range is encountered, func(obj, x) is called for each x in the Range. The objects returned by func populate the array in the order in which they are called. The return value is the new array. Type checking and conversion VALUE rb_check_array_type(VALUE ary); rb_check_array_type checks that ary is in fact an array, or convertible to an array via a to_ary method. If so, it returns the resulting array; otherwise, it returns Qnil. ---- VALUE rb_ary_to_ary(VALUE obj); rb_ary_to_ary checks that obj is in fact an array, or convertible to an array via a to_ary method. If so, it returns the resulting array; otherwise, it returns a new array whose single element is obj. ---- VALUE rb_ary_to_s(VALUE ary); rb_ary_to_s returns the string representation of ary. Setting array elements void rb_ary_store(VALUE ary, long idx, VALUE val); rb_ary_store stores the value val into the array ary at index idx. Negative indexes count from the end of the array. ---- VALUE rb_ary_unshift(VALUE ary, VALUE item); rb_ary_unshift prefixes the object item to the start of the array ary. The return value is ary, mainly because this function implements the Array#unshift method. ---- VALUE rb_ary_push(VALUE ary, VALUE item); rb_ary_push appends the object item to the end of the array ary. The return value is ary, mainly because this function implements the Array#push method. ---- VALUE rb_ary_replace(VALUE copy, VALUE orig); rb_ary_replace replaces the elements of copy with those of orig, so that copy is a shallow copy of orig. Retrieving array elements VALUE rb_ary_entry(VALUE ary, long idx); rb_ary_entry retrieves the element from ary at index idx. Negative indexes count from the end of the array. ---- VALUE rb_ary_shift(VALUE ary); rb_ary_shift removes the first element from ary and returns it. ary then has one less element than before, and the remaining elements appear at an index one less than before. ---- VALUE rb_ary_pop(VALUE ary); rb_ary_pop removes the last element from ary and returns it. ary then has one less element than before. ---- VALUE rb_ary_subseq(VALUE ary, long beg, long len); rb_ary_subseq returns a new array containing len elements, copied from ary starting at index beg. Negative indexes are not supported; if beg is negative or out of bounds, or len is negative, rb_ary_subseq returns Qnil. If beg+len exceeds the end of the array, the returned array will have fewer than len elements. ---- VALUE rb_ary_aref(int argc, VALUE *argv, VALUE ary); rb_ary_aref implements the Array#[] method. ---- VALUE rb_ary_each(VALUE ary); rb_ary_each returns an Enumerator over the array ary; or, if a block is given, it calls the block once for each element of the array, passing the elements of the array in order, one per call, and returns ary. Removing elements from an array VALUE rb_ary_delete(VALUE ary, VALUE item); rb_ary_delete removes elements from ary that are equal to item. The return value is item if any matches are found, or Qnil if not. If a block is given and there are no matches, rb_ary_delete calls the block and returns the return value of the block. ---- VALUE rb_ary_delete_at(VALUE ary, long idx); rb_ary_delete removes the element at position idx in the array ary, shifts all following elements downward one position, and returns the deleted element, or returns Qnil if idx is out of bounds. Negative indexes count from the end of the array. ---- VALUE rb_ary_clear(VALUE ary); rb_ary_clear deletes all elements of the array ary, and returns ary. Operations on arrays VALUE rb_ary_join(VALUE ary, VALUE sep); rb_ary_join returns a String, consisting of the string representations of each element of ary, joined by the String sep. ---- VALUE rb_ary_reverse(VALUE ary); rb_ary_reverse reverses the order of the elements of ary in place. ---- VALUE rb_ary_sort(VALUE ary); VALUE rb_ary_sort_bang(VALUE ary); rb_ary_sort returns a copy of ary, comparing them according to their own <=> method, or according to a block if one is provided. rb_ary_sort_bang is similar, except that it sorts ary in place and returns ary. ---- VALUE rb_ary_plus(VALUE ary1, VALUE ary2);/code> rb_ary_plus returns a new array consisting of array ary1 concatenated with array ary2. ---- VALUE rb_ary_concat(VALUE ary1, VALUE ary2); rb_ary_concat appends the contents of the array ary2 to those of ary1. It differs from rb_ary_plus in that it modifies ary1 in place. ---- VALUE rb_ary_assoc(VALUE ary, VALUE item); VALUE rb_ary_rassoc(VALUE, VALUE); rb_ary_assoc scans through the array ary, from beginning to end, and assumes that the elements of ary are themselves arrays; it returns the first such array whose first element matches item. rb_ary_rassoc is similar, but matches the second element of each array. It is intended for use with two-element arrays, such as are created by rb_assoc_new. The return value is Qnil if no element matches. ---- VALUE rb_ary_includes(VALUE ary, VALUE item); rb_ary_includes returns Qtrue if the item item is present in the array ary, else Qfalse. Use RTEST to convert the return value to a C Boolean. ---- VALUE rb_ary_cmp(VALUE ary1, VALUE ary2); rb_ary_cmp compares ary1 to ary2 by comparing the corresponding elements, beginning with 0. It returns a Fixnum corresponding to -1, 0, or +1 to indicate the result of the comparison, with a longer array being considered greater than a shorter one if no other mismatch is found. If ary2 is not an array, the return value is Qnil... Freezing VALUE rb_ary_freeze(VALUE ary); rb_ary_freeze freezes the object ary. This is presently equivalent to rb_obj_freeze. Uncategorized void rb_mem_clear(VALUE *mem, long size); rb_mem_clear sets each of size elements of mem to Qnil. It is not clear that this function is meant to be called by extensions. ---- VALUE rb_ary_tmp_new(long capa); rb_ary_tmp_new creates a new array and reserves space for capa elements. It differs from rb_ary_new in that it does not use rb_cArray as a base class, but uses Qnil instead. This is likely not meant to be called by extensions. ---- void rb_ary_free(VALUE ary); rb_ary_free frees memory attached to ary. This is likely not meant to be called by extensions.